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INTRODUCTION 

This document contains information about the Peek/Poke invokable module that was 
created for the Apple /// computer in 1982 for use by the Apple Ill's BASIC language 
interpreter, Apple /// Business BASIC. 

This invokable module allows Apple /// BASIC programmers to use PEEK and POKE 
commands which this BASIC'S command set does not support. This information 
consists of the programmer usage instructions, the peek/poke invokable module source 
listing from its parent article, and the source listing courtesy of the Washington Apple Pi 
(WAP) Apple /// disk archive. 

This source is written in 6502 assembly language for assembly by the Apple /// Pascal 
System 6502 assembler. 
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PEEK/POKE INVOKABLE USAGE INSTRUCTIONS 

Down to Business. The accompanying aasembly language 
program contains the function peek «md the procedure poke. It 
depends primarily on extended addressing but, regrettably, 
uses less legal methods as well. After assembly, the resulting 
code can either be linked to a Pascal program or invoked from 
Basic as an invokable module. It work* the same way in both 
languages. 

Peek is a function and returns an integer value, the con- 
tents of the memory location at which you've peeked. The func- 
tion requires two parameters. You must supply the address 
(as viewed by the 6602) and the Xbyte. Both are passed as In- 
tegers. In Pascal you declare peek an external function: 

function peck (addr, xb/t* > int*g*r) i intagtr; 
•xtarnol) 

You may then make an assignment statement to an integer 
variable : 

int i> pack (addr, xbyta); 

In Basic the process looks like this: 

10 INVOKE "p««k.pok*.cod*"> REM tha pothnam* of th* codafil*. 
100 int - EXFN%.paak(%oddr,%xbyta) 

Poke is similar, but since it doesn't return anything (ex- 
cept, occasionally, disaster) , it Is a procedure. It has a third 
parameter, the value to be poked. Value must also be an in- 
teger. 
In Pascal: 

procadura poka (addr, xbyta, valua i intagar); 
axtarnoli 

then one can use: 

volua i> 128; 

poka (addr, xbyta, valua); 
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In Basic: 

10 INVOKE "pMk.pok«.cod«" 
100 valu* - 128 

1 10 PERFORM pok*<%addr,%xbyt*,%valu«) 

Don't forget that the variables are all decimal Integers. You 
may want to enter them and display them as hexadecimal 
strings, but you will have to convert. Basic has handy built-lna: 
HEX$ (integer) and TEN(hexstring). In Pascal you will have 
to write your own. 

The address can be any legal, ordinary Integer. Value and 
Kbyte must be integers in the range to 256. If they are 
greater, the integer MOD £66 Is used. Only certain Xbyte 
values have meaning; all the rest are treated as 0. Table 2 haa 
some useful Xbytes and some comments. There are a couple of 
peculiarities that you should know about: 

1. Nothing terrible happens If you give the Xbyte of a bank 
pair that doesn't exist (yet)— for example, (|8C - 140). Peek 
win either return IFF, signifying nothing, or some value from 
one of the existing banks— also of little use. 

2. The artificial Xbyte IFF (decimal 266) isn't actually 
used as an Xbyte. It is merely a signal to the function to do all 
sorts of illegal things to the environment register, zero-page reg- 
ister, and Interrupts In order to get at areas normally inac- 
cessible. With tills "Xbyte" you get a block that looks Uke or- 
dinary (system) addressing but with "true" ze ro-pa ge and 
"true" (101) stack-page. Also, the area ICOOO to |CFFF is "I/O 
space," and IFOOO to |FFFF is the read-only memory used in 
the boot process. 

Hex Dacimol Rnult 

$00 "ordinary" lysKm bank. Umf bank at $2000..$9EFF 

J80 128 bank pair 0,1 

S82 130 bank pair 2,3 — bank 3 nonaxlilent in 128K machins 



S86 134 bonk pair 6,7 — bank 7 nonexistent in 256K machine 
$8F 1 43 like tyitem bank. Bonk to $2000..$9FFF. ALL RAMI 
$FF 255 "ortificial" — give* a lyttem type bank with 

1. "true" zero-page ond ita<k-page 

2. ICOOO to SCFFF = I/O tpaee 

3. SFOOO to SFFFF - ROM 
Table 2. Xbyte values. 
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Note: There are locationa on fClOO page of I/O space that 
cause the computer to "hang" Just by reading them. It 
really Isn't dangerous, but you'll have to reboot. 

A Program by Any Other Name. Boot up Pascal, enter the 
editor, and type In the program. Capital letters are not re- 
quired. Neither are the comments, but It would be a shame If 
you left out all of them. You can save a lot of typing by Just typ- 
ing in peek and duplicating It with the copy buffer. Then go 
through and make the necessary changes to convert one of 
them to poke. Save the program on disk. Use a path name of 
ten characters or less and permit the editor to add the suffix 
_TEXT to your path name (for example, peek.poke.text). 

Next, enter the assembler and assemble the program. The 
assembler will want to add the suffix .code. Let It. Otherwise 
the resulting file will not be type named code file and will not 
invoke properly. Later you can change the name (for exam- 
ple, peek.poke.inv) and the type name won't be affected. 

The output of the assembler is the Invokable module. Move 
it ! ; your Basic disk and Invoke It by Its path name. You can 
tht 1 use either peek or poke at will In your program. Details of 
the required Basic program syntax may be found starting on 
page 160 of the Apple III Basic Maniuil. 

Pascal Is even simpler. You Just declare peek and poke as 
external and use the linker to add them to your program. 
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PEEK.POKE.TEXT — Sourc* Cod* 



.MACRO 


POP 


PLA 




STA 


%1 


PLA 




STA 




.ENDM 




MACHO 


PUSH 


LOA 




PHA 




IDA 


%1 


PHA 




.ENDM 





ADDRESS 


.EQU 


0E8 


BANKSW 


.EQU 


OFFEF 


ZERCPG 


.EQU 


OFFOO 


ENVRMT 


.EQU 


OFFDF 




.FUNC 


PEEK,2 




JMP 


BEGIN 


RETURN 


.WORD 





XBYTE 


.WORD 





RESULT 


.WORD 





OLD_XBT 


.BYTE 





OLD_ZPG 


.BYTE 





ENV 


.BYTE 





BEGIN 


POP 


RETURN 




PLA 






PU 






PLA 






PLA 






POP 


XBYTE 




POP 


ADDRESS 




LOA 


ADDRESS+IMI 




STA 


OLD_ XBT 




LDA 


XBYTE 




CMP 


iWFF 




6EQ 


SPECIAL 




CMP 


#80 




BMI 


SYSTEM 




CMP 


*90 




BMI 


EXTEND 


SYSTEM 


LOY 


#0 




STY 


ADDRESS + 1601 




LOA 


C<i.ADDRESS.Y 




STA 


RESULT 




JMP 


DONE 


EXTEND 


STA 


ADDRESS -hi 601 




IDY 


#0 




LOA 


(<*ADDRESS,Y 




STA 


RESULT 



iKropag* "pMvdo" ragiittr 



/"dummy" byt« for function 

iporomotori com* off In rtvtrM order 

;fav« original x-byt* volu* 

;which bonk is dcsirod 

,FF-ROMi(H,C0-CF-l/O, 
I "trut" 00 ond 01 pag« 

j80-8F-aitt*nd«d oddrtuing 

I oIm lyitam bonk (ordinory 6502) 

fhondl* lyitem bonk 

;xbyte - M got ordinory 6502 
I indiroct Indoxod oddrwiing 



;handl« ntondod oddrouing to o 

bonkpoir or S8F 
;ploc« mttnd byt* 

)"*xt*ndad" oddmting to dotirod 
7 bonk pair 
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JMP 


DONE 






CMP 


#ODF 










;handta arttfictal bank TF' 




BEQ 


DONE 


;it you reolly want to crash, just start 


SPECIAL 


LDA 


ADDRESS +1 




CMP 


#OEF 


POKing into SOS 




BEQ 


TRUEPG5 


;tru* $00, SOI d«ir«d7 








(RAM $8800 - FFFF) 




CMP 






BEQ 


DONE 


; soon he will get very sick 




BEQ 


TBI IBD/^C 


iROm\ — > FOOOO-FFFF, 


S3 


LDA 


XBYTE 


;detect artificial bank 'FF' 




PHP 

SEI 

LDA 


CNVRMl 


COOO-CFFF— ^l/O 
;9av* ttotui, th«n disable interrupts 
;(an "illegal" move) 
;9ave environment 


SYSTEM 


CMP 
BEQ 

LDY 


f^OFF 
SPECIAL 

#0 


;FF - ROM #1, CO-CF « I/O 
; *'true" 00 and 01 pages 
;handle system bank 




STA 






STY 


ADDRESS+1601 


;xbyte = JO get ordinary 6502 




LDA 


*73 


;#% 01 n con - nvw environment 




LDA 
STA 


VALUE 

(a;ADDRESS,Y 


; indirect indexed addressing 




STA 


ENVRMT 


reg 

;(an "Illegal" move) 




JMP 


DONE 


;handle extended addressing to a 




LDY 


#0 










STY 




;system bank xbyte ^ 00 








bonkpoir or S8F 




LDA 


^ADDRcSS.T 


EXTEND 


STA 


ADDRESS + 1601 


jplace extend byte 




STA 


RESULT 






LDY 


#0 






LDA 


ENV 


;restore ENVRMT 




LDA 


VALUE 






STA 


CNVRMi 






STA 


(ft.ADDRESS,Y 


exTenoeo oooressing to aesiroo 




PLP 




;restore status (including interrupts) 
;deiired addreu on true 00 or 




JMP 


DONE 


; bonk poir 




JMP 


DONE 




jhondle artificial bonk *FF' 








01 page 
;save status, then disable interrupts 
,*(an "illegal" move) 


SPECIAL 


LDA 


ADDRESS + 1 




TBI IPDnC 


PHP 
SEI 






BEO 
CMP 


TRUEPGS 
#1 


;true zp or $01 desired? 




LDX 


ADDrcSS 


jlood BEFORE leaving old i-page 




BEQ 


TRUEPGS 






LDY 










;ROM#l — > F000-FFFF,COOO-CFFF 




LDA 


ZEROPG 


;»ave old zpg 








>i/o 




STA 


OLD LrG 




PHP 




;sove status, then disable interruT''' 




LDA 




;cnanges xero-page to 0, stock to i 




SEI 




'(on ^ illegal" move) 




STA 


ZEROPG 


;(an "illegal" move) 




IDA 


ENVRMT 


;save environment 




TYA 




;i» highb/teOOorOI 




STA 


ENV 






BEQ 


SI 






LDA 


#73 


;#%011t 0011 - new environment 




LDA 


0100,X 


;lndexed addressing (x ~ addr) 








rog 




JMP 


S2 






STA 


ENVRMT 


f(an ^ illegol" move) 


$1 




0000, X 






LDY 








STA 


RESULT 






STY 


ADDRESS +1601 


^system oonK xDyte " W 






OLD ZPG 


jrettore ZEROPG (and stack page) 




LDA 


VALUE 






STA 






STA 


(auAUUKC33,T 






PLP 




;restore interrupts (status) 




LDA 




;rettore ENVRMT 


DONE 


LDA 

STA 

PUSH 

PUSH 

RTS 


OLD XBT 

AL^URC99^ lOUf 

RESULT 

KcTUKN 


;re>lDre Pascal's xbyte 




STA 
PLP 
JMP 




.... 

jrestore status (including interrtj:. . 

;deslred address on true 00 or 01 
page 




.PROC 


POKE, 3 




TRUEPGS 


PHP 




;save status, then disoble interrupts 




JMP 


BEGIN 






SEI 




;(an "illegal" move) 


DBTI IBM 


.WORD 









LDX 


ADDRESS 


;load BEFORE leaving old z-poge 


XBYTE 


.WORD 









LDY 


ADDRE5S+1 


VALUE 


WORD 


f% 

V 






LDA 


ZEROPG 


;save old zpg 


OLD XBT 


.BYTE 









STA 


OLD ZPG 


OLD ZPG 


BYTE 


Q 






LDA 


#0 


;changes zero page to 0, stock to I 


\J\.U— CP4V 


-BYTE 









STA 


ZEROPG 


;(an "illegal" move) 


ENV 


.BYTE 









LDA 


VALUE 


BEGIN 


POP 


BETI IBM 


;parometers come off in reverse order 




CPY 


#0 


;is high byte 00 or 01 




POP 


VALUE 






BEQ 


SI 












STA 


0100,X 


.-indexed addressing (x addr) 




POP 








JMP 


$2 




LDA 


ADDRESS 4-1 A0 1 


jsave original x^oyte value 






• 0000,X 






STA 


OLD_XBT 




S2 


LDA 


OLD— ZPG 


;restorB ZEROPG (and stack page) 




LDA 


ENVRMT 


■save ENVRMT 




STA 


ZEROPG 






STA 


OLD_ ENV 






PLP 




;restore interrupts (status) 




AND 


#0F7 


jfor POKE, enable write COOO to FFFF 


DONE 


LDA 


OLD— XBT 


;restore Pascal's xbyte 

.restore CO-CF read/write status 




STA 


ENVRMT 


;which bank is desired 




STA 
LDA 


ADDRESS+1601 
OLD_ENV 




LDA 


XBYTE 






STA 


ENVRMT 






CMP 


m 






PUSH 


RETURN 






BMI 


$1 


;80-8F'extended oddressing 




RTS 








CMP 


#90 


t else system bonk (ordinary 6502) 




.END 




1 




BMt 


EXTEND 


;disollow certoin oddresses 










$1 


LDA 
CMP 
BNE 

LDA 
CMP 
BEQ 


ADDRESS + 1 
$2 

ADDRESS 

ifOOO 

DONE 


;POKE disolbwed at (system bank)i 
i BANKSW - FFEF 
; ENVRMT - FFDF 

; ZEROPG » mo 

! in this program — suicide certain 
J in your program — suicide probable 
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The procedure PEEK and the function POKE 
written by John Jeppson 

published in SOFTALK magazine: AUG 82 in the article 

BANK SWITCH RAZZLE DAZZLE: Peeking and Poking the Apple /// 



MACROS 



.MACRO POP 
PLA 



STA 
PLA 
STA 
.ENDM 



%1 

%1+1 



.MACRO PUSH 



LDA 
PHA 
LDA 
PHA 
.ENDM 



%1 



EQUATES 



ADDRESS 


.EQU 


0E8 


BANKSW 


.EQU 


0FFEF 


ZEROPG 


.EQU 


0FFD0 


ENVRMT 


.EQU 


0FFDF 


; @@@@@( 
; @@@@@( 


'.FUNC 
J@@@@@@( 


PEEK, 2 




JMP 


BEGIN 


RETURN 


.WORD 





XBYTE 


.WORD 





RESULT 


.WORD 





OLDXBT 


.BYTE 





OLDZPG 


.BYTE 





ENV 


.BYTE 





BEGIN 


POP 


RETURN 




PLA 






PLA 






PLA 






PLA 






POP 


XBYTE 




POP 


ADDRESS 



:zeropage "pseudo" register 



"dummy" bytes for function 



: parameters come off in reverse order 
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LDA ADDRESS+1601 ;save original x-byte value 

STA OLDXBT 

;which bank is desired 

LDA XBYTE 

CMP #0FF ;FF = ROM #1, C0-CF = I/O, 

BEQ SPECIAL ; "true" 00 and 01 pages 

CMP #80 

BMI SYSTEM ; 80-8F=extended addressing 

CMP #90 ; else system bank (ordinary 6502) 

BMI EXTEND 

;handle system bank 

SYSTEM LDY #0 

STY ADDRESS+1601 ;xbyte = so get ordinary 6502 

LDA @ADDRESS,Y ; indirect indexed addressing 

STA RESULT 

JMP DONE 

;handle extended addressing to a bankpair or $8F 

EXTEND STA ADDRESS+1601 ; place extend byte 

LDY #0 

LDA ©ADDRESS, Y ;"extended" addressing to desired 

STA RESULT ; bank pair 

JMP DONE 

;handle artifical bank 'FF' 

SPECIAL LDA ADDRESS+1 

BEQ TRUEPGS ;true $00, $01 desired? 

CMP #1 

BEQ TRUEPGS 

;R0M#1 --> F000-FFFF, C000-CFFF --> I/O 
PHP ;save status, then disable interrupts 

SEI ; (an "illegal" move) 

LDA ENVRMT ;save environment 

STA ENV 

LDA #73 ;#% 0111 0011 - new environment reg 

STA ENVRMT ; (an "illegal" move) 

LDY #0 

STY ADDRESS+1601 ; system bank xbyte = 00 

LDA @ADDRESS,Y 

STA RESULT 

LDA ENV ; restore ENVRMT 

STA ENVRMT 

PLP ; restore status (including interrupts) 

JMP DONE 

;desired address on true 00 or 01 page 
TRUEPGS PHP ;save status, then disable interrupts 

SEI ; (an "Illegal" move) 

LDX ADDRESS ;load BEFORE leaving old z-page 

LDY ADDRESS+1 

LDA ZEROPG ;save old zpg 

STA OLDZPG 

LDA #0 ;changes zero-page to 0, stack to 1 

STA ZEROPG ;(an "illegal" move) 
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TYA 




;is high byte 00 or 01 




BEQ 


$1 






LDA 


0100, X 


;indexed addressing (x = addr) 




J MP 


52 


$1 


LDA 


0000, X 




$2 


STA 


RESULT 






LDA 


OLDZPG 


; restore ZEROPG (and stack page) 




STA 


ZEROPG 




PLP 




;restore interrupts (status) 


DONE 


LDA 


OLDXBT 


;restore Pascal's xbyte 




STA 


ADDRESS+1601 






PUSH 


RESULT 






PUSH 


i-\ r" "T" 1 1 L 1 

RETURN 






RTS 






; @@@@@ 
; @@@@@ 


@@@@@@ 

.PROC 

@@@@@@ 


POKE, 3 


@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ 




JMP 


BEGIN 




RETURN 


.WORD 







XBYTE 


.WORD 







VALUE 


.WORD 







OLDXBT 


.BYTE 







OLDZPG 


. BYTE 







OLDENV 


.BYTE 







ENV 


.BYTE 







BEGIN 


POP 


RETURN 


;parameters come off in reverse order 




POP 


VALUE 






POP 


XBYTE 






POP 


ADDRESS 






LDA 


ADDRESS+1601 


;save original x-byte value 




STA 


OLDXBT 






LDA 


ENVRMT 


;save ENVRMT 




STA 


OLDENV 






AND 


#0F7 


;for POKE, enable write C000 to FFFF 




STA 


ENVRMT 








;which bank is desired 






LDA 


XBYTE 






CMP 


#80 






BMI 


$1 


; 80-8F=extended addressing 




CMP 


#90 


; else system bank (ordinary 6502) 




BMI 


EXTEND 








;disallow certain addresses 




$1 


LDA 


ADDRESS+1 


;POKE disallowed at (system bank): 




CMP 


#0FF 


; BANKSW = FFEF 




BNE 


$2 


; ENVRMT = FFDF 



Apple /// Computer Information Page 9 of 1 1 

Apple /// Business BASIC Peek/Poke Invokable Module Information 

Bank Switch Razzle-Dazzle: Peeking and Poking thie Apple /// 

Dr. John Jeppson -- SOFTALK magazine, August 1982, pages 38-48 



Apple /// Computer Information 



; ZER0P6 = FFD0 

LDA ADDRESS 

CMP #0D0 ; in this program - suicide certain 

BEQ DONE ; in your program - suicide probable 

CMP #0DF 

BEQ DONE ;if you really want to crash, just star 

CMP #0EF ; POKing Into SOS (RAM $B800 - FFFF) 

BEQ DONE ; soon he will get very sick 

;detect artificial bank 'FF' 
$2 LDA XBYTE 

CMP #0FF ;FF = ROM #1, C0-CF = I/O 

BEQ SPECIAL ; "true" 00 and 01 pages 

;handle system bank 
SYSTEM LDY #0 

STY ADDRE5S+1601 ;xbyte = so get ordinary 6502 

LDA VALUE ; indirect indexed addressing 

STA @ADDRESS,Y 
JMP DONE 

;handle extended addressing to a bankpair or $8F 
EXTEND STA ADDRESS+1601 ; place extend byte 

LDY #0 
LDA VALUE 

STA (SADDRESS.Y ; "extended" addressing to desired 

; bank pair 

JMP DONE 

;handle artifical bank 'FF' 
SPECIAL LDA ADDRESS+1 

BEQ TRUEPGS ;true zp or $01 desired? 

CMP #1 

BEQ TRUEPGS 

;R0M#1 --> F000-FFFF, C000-CFFF --> I/O 

PHP ;save status, then disable interrupts 

SEI ; (an "illegal" move) 

LDA ENVRMT ;save environment 

STA ENV 

LDA #73 ;#% 0111 0011 - new environment reg 

STA ENVRMT ; (an "illegal" move) 

LDY #0 

STY ADDRESS+1601 ; system bank xbyte = 00 

LDA VALUE 

STA ©ADDRESS, Y 

LDA ENV ; restore ENVRMT 

STA ENVRMT 

PLP ;restore status (including interrupts) 

JMP DONE 

;desired address on true 00 or 01 page 
TRUEPGS PHP ;save status, then disable interrupts 

SEI ; (an "illegal" move) 

LDX ADDRESS ;load BEFORE leaving old z-page 

LDY ADDRESS+1 
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LDA 


ZEROPG 


;save old zpg 


c "r A 


r\ 1 r\ 7 Dr" 
ULDZr(j 




LDA 


#0 


;changes zero page to 0, stack to 


STA 


ZEROPG 


; (an " i llegal " move) 


LDA 


VALUE 




CPY 


#0 


;is high byte 00 or 01 


BEQ 


$1 




STA 


0100, X 


;indexed addressing (x = addr) 


J MP 


52 




STA 


0000, X 




LDA 


OLDZPG 


; restore ZEROPG (and stack page) 


STA 


ZEROPG 




PLP 




; restore interrupts (status) 


LDA 


QLDXBT 


; restore Pascal's xbyte 


STA 


ADDRES5+1601 




LDA 


OLDENV 


;restore C0-CF read/write status 


STA 


ENVRMT 




PUSH 


RETURN 




RTS 






.END 







END OF INFORMATION 
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